home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / lib / mozilla-firefox / idl / nsIChannel.idl < prev    next >
Text File  |  2006-05-08  |  9KB  |  220 lines
  1. /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
  2. /* ***** BEGIN LICENSE BLOCK *****
  3.  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  4.  *
  5.  * The contents of this file are subject to the Mozilla Public License Version
  6.  * 1.1 (the "License"); you may not use this file except in compliance with
  7.  * the License. You may obtain a copy of the License at
  8.  * http://www.mozilla.org/MPL/
  9.  *
  10.  * Software distributed under the License is distributed on an "AS IS" basis,
  11.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12.  * for the specific language governing rights and limitations under the
  13.  * License.
  14.  *
  15.  * The Original Code is mozilla.org code.
  16.  *
  17.  * The Initial Developer of the Original Code is
  18.  * Netscape Communications Corporation.
  19.  * Portions created by the Initial Developer are Copyright (C) 1998
  20.  * the Initial Developer. All Rights Reserved.
  21.  *
  22.  * Contributor(s):
  23.  *
  24.  * Alternatively, the contents of this file may be used under the terms of
  25.  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26.  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27.  * in which case the provisions of the GPL or the LGPL are applicable instead
  28.  * of those above. If you wish to allow use of your version of this file only
  29.  * under the terms of either the GPL or the LGPL, and not to allow others to
  30.  * use your version of this file under the terms of the MPL, indicate your
  31.  * decision by deleting the provisions above and replace them with the notice
  32.  * and other provisions required by the GPL or the LGPL. If you do not delete
  33.  * the provisions above, a recipient may use your version of this file under
  34.  * the terms of any one of the MPL, the GPL or the LGPL.
  35.  *
  36.  * ***** END LICENSE BLOCK ***** */
  37.  
  38. #include "nsIRequest.idl"
  39.  
  40. interface nsIURI;
  41. interface nsIInterfaceRequestor;
  42. interface nsIInputStream;
  43. interface nsIStreamListener;
  44.  
  45. /**
  46.  * The nsIChannel interface allows clients to construct "GET" requests for
  47.  * specific protocols, and manage them in a uniform way.  Once a channel is
  48.  * created (via nsIIOService::newChannel), parameters for that request may
  49.  * be set by using the channel attributes, or by QI'ing to a subclass of
  50.  * nsIChannel for protocol-specific parameters.  Then, the URI can be fetched
  51.  * by calling nsIChannel::open or nsIChannel::asyncOpen.
  52.  *
  53.  * After a request has been completed, the channel is still valid for accessing
  54.  * protocol-specific results.  For example, QI'ing to nsIHttpChannel allows
  55.  * response headers to be retrieved for the corresponding http transaction. 
  56.  *
  57.  * @status FROZEN
  58.  */
  59. [scriptable, uuid(c63a055a-a676-4e71-bf3c-6cfa11082018)]
  60. interface nsIChannel : nsIRequest
  61. {
  62.     /**
  63.      * The original URI used to construct the channel. This is used in the case
  64.      * of a redirect or URI "resolution" (e.g. resolving a resource: URI to a
  65.      * file: URI) so that the original pre-redirect URI can still be obtained. 
  66.      *
  67.      * NOTE: this is distinctly different from the http Referer (referring URI),
  68.      * which is typically the page that contained the original URI (accessible
  69.      * from nsIHttpChannel).
  70.      */
  71.     attribute nsIURI originalURI;
  72.  
  73.     /**
  74.      * The URI corresponding to the channel.  Its value is immutable.
  75.      */
  76.     readonly attribute nsIURI URI;
  77.  
  78.     /**
  79.      * The owner, corresponding to the entity that is responsible for this
  80.      * channel.  Used by the security manager to grant or deny privileges to
  81.      * mobile code loaded from this channel.
  82.      *
  83.      * NOTE: this is a strong reference to the owner, so if the owner is also
  84.      * holding a strong reference to the channel, care must be taken to 
  85.      * explicitly drop its reference to the channel.
  86.      */
  87.     attribute nsISupports owner;
  88.  
  89.     /**
  90.      * The notification callbacks for the channel.  This is set by clients, who
  91.      * wish to provide a means to receive progress, status and protocol-specific 
  92.      * notifications.  If this value is NULL, the channel implementation may use
  93.      * the notification callbacks from its load group.  The channel may also
  94.      * query the notification callbacks from its load group if its notification
  95.      * callbacks do not supply the requested interface.
  96.      * 
  97.      * Interfaces commonly requested include: nsIProgressEventSink, nsIPrompt,
  98.      * and nsIAuthPrompt.
  99.      *
  100.      * When the channel is done, it must not continue holding references to
  101.      * this object.
  102.      *
  103.      * NOTE: A channel implementation should take care when "caching" an
  104.      * interface pointer queried from its notification callbacks.  If the
  105.      * notification callbacks are changed, then a cached interface pointer may
  106.      * become invalid and may therefore need to be re-queried.
  107.      */
  108.     attribute nsIInterfaceRequestor notificationCallbacks;
  109.  
  110.     /**
  111.      * Transport-level security information (if any) corresponding to the channel.
  112.      */
  113.     readonly attribute nsISupports securityInfo;
  114.  
  115.     /**
  116.      * The MIME type of the channel's content if available. 
  117.      * 
  118.      * NOTE: the content type can often be wrongly specified (e.g., wrong file
  119.      * extension, wrong MIME type, wrong document type stored on a server, etc.),
  120.      * and the caller most likely wants to verify with the actual data.
  121.      *
  122.      * Setting contentType before the channel has been opened provides a hint
  123.      * to the channel as to what the MIME type is.  The channel may ignore this
  124.      * hint in deciding on the actual MIME type that it will report.
  125.      *
  126.      * Setting contentType after onStartRequest has been fired or after open()
  127.      * is called will override the type determined by the channel.
  128.      *
  129.      * Setting contentType between the time that asyncOpen() is called and the
  130.      * time when onStartRequest is fired has undefined behavior at this time.
  131.      *
  132.      * The value of the contentType attribute is a lowercase string.  A value
  133.      * assigned to this attribute will be parsed and normalized as follows:
  134.      *  1- any parameters (delimited with a ';') will be stripped.
  135.      *  2- if a charset parameter is given, then its value will replace the
  136.      *     the contentCharset attribute of the channel.
  137.      *  3- the stripped contentType will be lowercased.
  138.      * Any implementation of nsIChannel must follow these rules.
  139.      */
  140.     attribute ACString contentType;
  141.  
  142.     /**
  143.      * The character set of the channel's content if available and if applicable.
  144.      * This attribute only applies to textual data.
  145.      *
  146.      * The value of the contentCharset attribute is a mixedcase string.
  147.      */
  148.     attribute ACString contentCharset;
  149.  
  150.     /**
  151.      * The length of the data associated with the channel if available.  A value
  152.      * of -1 indicates that the content length is unknown.
  153.      *
  154.      * Callers should prefer getting the "content-length" property
  155.      * as 64-bit value by QIing the channel to nsIPropertyBag2,
  156.      * if that interface is exposed by the channel.
  157.      */
  158.     attribute long contentLength;
  159.  
  160.     /**
  161.      * Synchronously open the channel.
  162.      *
  163.      * @return blocking input stream to the channel's data.
  164.      *
  165.      * NOTE: nsIChannel implementations are not required to implement this
  166.      * method.  Moreover, since this method may block the calling thread, it
  167.      * should not be called on a thread that processes UI events.
  168.      */
  169.     nsIInputStream open();
  170.  
  171.     /**
  172.      * Asynchronously open this channel.  Data is fed to the specified stream
  173.      * listener as it becomes available.  The stream listener's methods are
  174.      * called on the thread that calls asyncOpen and are not called until
  175.      * after asyncOpen returns.
  176.      *
  177.      * @param aListener the nsIStreamListener implementation
  178.      * @param aContext an opaque parameter forwarded to aListener's methods
  179.      */
  180.     void asyncOpen(in nsIStreamListener aListener, in nsISupports aContext);
  181.  
  182.     /**************************************************************************
  183.      * Channel specific load flags:
  184.      *
  185.      * Bits 21-31 are reserved for future use by this interface or one of its
  186.      * derivatives (e.g., see nsICachingChannel).
  187.      */
  188.  
  189.     /**
  190.      * Set (e.g., by the docshell) to indicate whether or not the channel
  191.      * corresponds to a document URI.
  192.      */
  193.     const unsigned long LOAD_DOCUMENT_URI = 1 << 16;
  194.  
  195.     /** 
  196.      * If the end consumer for this load has been retargeted after discovering 
  197.      * it's content, this flag will be set:
  198.      */
  199.     const unsigned long LOAD_RETARGETED_DOCUMENT_URI = 1 << 17;
  200.  
  201.     /**
  202.      * This flag is set to indicate that onStopRequest may be followed by
  203.      * another onStartRequest/onStopRequest pair.  This flag is, for example,
  204.      * used by the multipart/replace stream converter.
  205.      */
  206.     const unsigned long LOAD_REPLACE = 1 << 18;
  207.  
  208.     /**
  209.      * Set (e.g., by the docshell) to indicate whether or not the channel
  210.      * corresponds to an initial document URI load (e.g., link click).
  211.      */
  212.     const unsigned long LOAD_INITIAL_DOCUMENT_URI = 1 << 19;
  213.  
  214.     /**
  215.      * Set (e.g., by the URILoader) to indicate whether or not the end consumer
  216.      * for this load has been determined.
  217.      */
  218.     const unsigned long LOAD_TARGETED = 1 << 20;
  219. };
  220.